BluetoothCharacteristic PRO#

The BluetoothCharacteristic interface represents a Bluetooth Low Energy (BLE) characteristic, which is the fundamental data unit in a BLE service. A characteristic exposes a specific piece of data and supports operations such as reading, writing, or subscribing to notifications.

1. Properties#

uuid: string#

The universally unique identifier (UUID) of the characteristic.

• Used to identify standard (e.g., "2A37" for Heart Rate Measurement) or custom vendor-defined characteristics.

serviceUUID: string | null#

The UUID of the service that contains this characteristic. May be null if the service is not known or not yet discovered.

properties: BluetoothCharacteristicProperty[]#

An array of supported operations for this characteristic. These define how the characteristic can be interacted with (read, write, notify, etc.).

Available Values (BluetoothCharacteristicProperty):#

Example:

1if (characteristic.properties.includes("read")) {
2  const value = await peripheral.readValue(characteristic)
3}

isNotifying: boolean#

Indicates whether notifications or indications are currently enabled for the characteristic.

• true: Notifications or indications are active
• false: Notifications are not active

value: Data | null#

The current value of the characteristic, as a Data object.

• May be null if the value has not yet been read or written.
• Use peripheral.readValue(characteristic) to fetch the latest value.

2. Attribute Permissions#

Although not directly present in the characteristic interface, attributes may be configured with permissions when used in a Peripheral (GATT Server) role.

BluetoothAttributePermissions (Enum)#

3. Usage Examples#

Read from a characteristic (requires "read")#

1if (characteristic.properties.includes("read")) {
2  const value = await peripheral.readValue(characteristic)
3  console.log("Value:", value?.toRawString())
4}

Write to a characteristic#

1const data = Data.fromRawString("COMMAND")
2if (characteristic.properties.includes("writeWithoutResponse")) {
3  await peripheral.writeValue(characteristic, data, "withoutResponse")
4} else if (characteristic.properties.includes("write")) {
5  await peripheral.writeValue(characteristic, data, "withResponse")
6}

Subscribe to notifications#

1if (characteristic.properties.includes("notify")) {
2  await peripheral.subscribe(characteristic, (error, value) => {
3    if (!error && value) {
4      console.log("Notification received:", value.toHexString())
5    }
6  })
7}

Unsubscribe from notifications#

1await peripheral.unsubscribe(characteristic)

4. Best Practices and Notes#

• Always call discoverCharacteristics(service) before interacting with any characteristic.
• Do not assume all characteristics support read/write; check properties before performing operations.
• When subscribing to notifications or indications, you must explicitly call subscribe() and later unsubscribe() to clean up.
• For "writeWithoutResponse" operations, use canSendWriteWithoutResponse to control flow rate.
• Before writing, use maxWriteValueLength() to ensure the data size is within limits.